home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Franz PD / Franz PD Disk #283 (1993)(Rhein-Sieg-Soft)[b dump].zip / Franz PD Disk #283 (1993)(Rhein-Sieg-Soft)[b dump].adf / tracker / Readme < prev    next >
Text File  |  1989-02-25  |  6KB  |  127 lines
  1. C Programmer's Amiga Resource Tracking Routines    Version 0.0a   1/5/89
  2. -------------------------------------------------------------------------
  3.  
  4. This code and documentation is released to the Public Domain without any
  5. restrictions on use, resale or redistribution.
  6.  
  7. No license or warranty of appropriateness, usefulness or bug-freeness is
  8. expressed or implied.  This is free code.  We don't have a contract.
  9.  
  10. Written by:
  11.  
  12. Karl Lehenbauer, Hackercorp, 3918 Panorama, Missouri City, TX, USA  77459
  13. (713) 438-4964 voice,  (713) 438-5018 data
  14. Usenet: uunet!sugar!karl, Internet: karl@sugar.uu.net, BIX: kelehen
  15.  
  16.  
  17. These routines were written to aid C programmers in insuring that their
  18. programs are  properly returning all the memory, signals and locks they
  19. have allocated.  
  20.  
  21. To use them, include tracker.h in your C source programs and recompile.
  22. (The use of an "includes.c" along with the Manx +i and +h flags to
  23. precompile the symbol table obviates the necessity of editing 
  24. '#include "tracker.h">' into every one of your source files.)
  25. Next, edit your exit routine to call TrackerExitReport() after it has
  26. freed everything.  Then, compile tracker.c using the memory model you're 
  27. using for the rest of your code and link your program to include tracker.o.
  28. (This can all be done in your makefile if you've got it set up right.)
  29. Finally, run your program.
  30.  
  31. The program must either be initiated from the CLI or you must edit your 
  32. program's startup code to fopen stderr and direct it somewhere  (like 
  33. to a  window or a file) or you won't get any of the resource tracker's 
  34. messages, or worse.
  35.  
  36. As your program runs, every time it allocs memory via AllocMem(), allocs
  37. a signal via AllocSignal() or gets a Lock via Lock(), special tracking
  38. routines execute instead (thanks to some macros defined by tracker.h)
  39. which, in addition to performing the action you requested, record 
  40. information about what you requested and what you got.  For AllocMem(),
  41. the source file and line of the AllocMem call as well as the amount of memory
  42. requested and the pointer to the memory returned are recorded.  For
  43. AllocSignal(), only the signal numbers allocated are recorded at this time.
  44. For Lock(), the file name to be locked, source file and line number and 
  45. the lock returned are recorded.
  46.  
  47. When your program frees memory via FreeMem(), a special tracking version
  48. of FreeMem is executed that searches the list of entries recorded by the
  49. tracking version of AllocMem().  The resource tracker reports if you free
  50. something more than once, if you free something that you didn't allocate
  51. or if the length that you are freeing differes from what you allocated.
  52. This includes the source file name and line number of the matching AllocMem 
  53. (when it is known) and always includes the source file and line for FreeMem.
  54.  
  55. When your program frees a signal via FreeSignal(), a tracking version
  56. of FreeSignal checks to see if you have allocated the signal you are
  57. now freeing.  If you haven't, it reports it, but it doesn't include the
  58. file name and line number at this time.  I don't think this is a serious
  59. problem, as signals aren't as critical as the other stuff, but I may add
  60. it in a future version.
  61.  
  62. When your program unlocks a lock via UnLock(), a tracking version of UnLock
  63. searches the list of recorded locks to see if you locked the lock you are
  64. unlocking and report accordingly.
  65.  
  66. The tracker exit report provided by TrackerExitReport() is where most of
  67. the bugs are identified.  TrackerExitReport identifies all AllocMems that
  68. didn't have a corresponding FreeMem, including the source file and line
  69. of the call to AllocMem as well as the address and size of the memory
  70. in question.  The resource tracker does not free the memory for you because
  71. you may have not freed the memory on purpose (for example, you may have
  72. spawned a task that uses it will free it later) and it cannot know that.
  73.  
  74. The exit report details all signals that weren't freed.  This isn't very
  75. important, in my opinion.
  76.  
  77. Also, the exit report prints information on all file locks that were made
  78. that didn't have a corresponding UnLock.  This information includes the
  79. name of the file, value of the lock and the source file and line of the
  80. code that locked it.
  81.  
  82. The exit report also prints the number of calls to allocate and free memory,
  83. allocate and free signals and to lock and unlock files as a gross indicator
  84. of whether you're cleaning everything up properly.
  85.  
  86. Note that, in the default configuration, memory that is freed and 
  87. reallocated will screw up the tracker because the tracker continues 
  88. to track memory objects after they have been  freed. This is a tradeoff 
  89. between being to be able to detect multiple frees of the same memory or 
  90. not.  If that's a problem, tracker.c can be recompiled with a
  91. -DFORGET_MEMORY_WHEN_FREED option so that it will not try to detect
  92. multiple frees.
  93.  
  94. The same is true for the lock tracking routines, although in that case 
  95. the argument is more clear that unlocks should cause the lock tracking 
  96. entry to be discarded, because multiple unlocks are common and multiple 
  97. locks and unlocks of the same file  during execution are also conceivably 
  98. pretty common.  Right now by default, the tracker will track locks after
  99. they have been freed.  To change this behavior, recompile tracker.c with
  100. the -DFORGET_LOCKS_WHEN_UNLOCKED option.
  101.  
  102. Unfortunately, the tracker macros that redefine AllocMem and such will
  103. cause your compiler to barf on any files you have that declare them
  104. as external.  If that happens, either remove the external declarations
  105. (and include <functions.h>) or move them to be before the include of
  106. tracker.h.
  107.  
  108.  
  109. ALPHA RELEASE, SOFTWARE STATUS
  110. ------------------------------
  111.  
  112. The Lock, Unlock and DupLock tracking routines have not been tested
  113. adequately.  The signal stuff works OK, but that's no biggie.  The
  114. main thing of interest is the tracking AllocMem and FreeMem, which
  115. I have used successfully on several programs that I have been working
  116. on.
  117.  
  118. -karl @ The Hacker's Haven, Houston, TX -- 5-Jan-89
  119.  
  120. P.S.  Note that TrackerExitReport() must be called to get the tracking
  121.  routines to free the memory they have allocated, so it's a good idea
  122.  to call it from your abnormal exit (_abort, etc) routines as well as
  123.  normal exit.  Also, that's good because you can make sure you're freeing
  124.  properly from your strange abort conditions, a thing that's hard to get
  125.  right.
  126.  
  127.